Front end features of MacPerl Matthias Neeracher 03Dec94This file describes features only present in the MacPerl application, whichare not directly related to the language itself.1. USER INTERFACEThis area is notoriously underdocumented. I can't give more than hints at the moment(I have a standing offer to write decent manuals if anybody researches and writes my PhD thesis for me :-):a) Online HelpSelecting any perl operator and choosing Help from the Help menu (That's the question mark icon on the right side of the menubar) will give you chapter and verse from thePerl manual page.If you turn on Balloon Help and point at a Perl operator, a balloon will give youa summary of parameters to the operator.a) MenusMacPerl for the most part tries to behave like a typical primitive text editor."Format" in the Edit menu presents a choice of text fonts and sizes. "Preferences"controls many settings, the most important of which is a list of library folders."Jump toﾉ" in the Edit menu allows to pop up files and lines based on the current selection. The following formats are supported: Format Example /File¥s+["']([^"']+)["']¥D*(¥d+)/i File "om:mani:padme:hum", Line 23 /["']([^"']+)["']¥D*(¥d+)/ "om:mani:padme:hum", Line 23 /["']([^"']+)["']/ "om:mani:padme:hum" /.+/ om:mani:padme:hum 2. PACKAGESA MacPerl file can be saved in various forms, depending on what you choose from the popup menu in the "Save As..." dialog: - A plain text file. These can be opened from any text editor or word processor. - A droplet. This combines the script and some glue code into a "Mini-application". These will automatically run when double-clicked from the finder, and all files you drop on them in the Finder will appear in the @ARV array. - A runtime. While they in some respects behave like droplets, they are much more heavyweight and will set you back several 100K every time you save one. The advantage of runtimes is that they run without the MacPerl application. - Any other packaging you could think of. A MacHTTP package will appear in a few days. The release verson of MacPerl 4.1.4 will describe how to add packaging options to MacPerl.3. APPLEEVENTS/APPLESCRIPTMacPerl has been scriptable and recordable since version 4.1.0. Most AppleEventssupported are the fairly conventional text events you'll find in the ScriptableText Editor. In fact, MacPerl should support pretty much the same text manipulationsas STE, except that STE generates somewhat prettier scripts when being recorded. Ifyou find something working in STE and not in MacPerl, talk to me about it!The only two events that are somewhat special to MacPerl are Save and Do Script.Event: Save [core/save]Direct parameter: A window object reference [obj ], a file [fss ], or text [TEXT]"in" [dest] (opt): A file [fss ] to save in."as" [fltp] (opt): A save type [svas] (standard types are Text [TEXT], Droplet [SCPT] and System 7 runtime [MrP7] or an enumeration cast to [svas]).This event does the same as the core save event, but it can also save files not openat the time and even on-the-fly text, and it can save in any package available. Thisis useful to e.g. save a file as a MacPerl droplet from another application.Event: "Do Script" [misc/dosc]Direct parameter: A file [fss ], text [TEXT] or a list of files and text.Reply: Text results, depending on mode."extract" [EXTR] (opt): A boolean [bool] which when false prevents searching for a #! line."debug" [DEBG] (opt):A boolean which when true runs the Perl debugger"mode" [MODE] (opt): A mode [MODE], one of Local [LOCL], Batch [BATC], Remote [RCTL], or Duplex [DPLX]."environment" [ENVT] (opt): A list of text [TEXT] variable/value pairs to add to the environment.[SASE] (opt): A record used as a callback event for remote mode.As opposed to the standard "Do Script" event, MacPerl's "Do Script" accepts a list asthe direct parameter and stuffs all further elements into @ARGV. The mode parameterhas a major influence on the way the script is executed: - Local mode is the default. The script just runs and only returns text if you call &MacPerl'Reply(). - Batch mode redirects standard output and error to the reply apple event. Standard output is put into the direct parameter of the reply, while standard error is put into element [diag] of parameter [OUTP]. - Remote control mode returns immediately from the DoScript request. Clients are then expected to communicate with MacPerl with "Send Data" [McPL/DATA] events. These contain standard input in the direct parameter and output as explained above. Furthermore, the 'WANT' parameter of the reply contains enumeration codes for all input descriptors awaiting input. Sending a null descriptor with any code signals an end of file for that file. MacPerl sets a boolean DONE parameter in its reply to signal the last data being sent. If you did specify a SASE parameter in your Do Script or Send Data events, it will be sent back to you the next time MacPerl waits for input. - Duplex is an often faster variant of Remote Control mode. The difference is that in Duplex mode, MacPerl will initiate I/O itself by putting actual data in the SASE events it sends out. Please see below for examples of interaction in Remote Control and Duplex mode. - Both Batch and Remote control/Duplex mode support opening further input and output streams as "Dev:AEVT:[4 byte code]". Standard input/output is "Dev:AEVT", standard error is "Dev:AEVT:diag". Note that these names are case sensitive!Furthermore, you can specify environment settings which will show up in %ENV in theenvironment parameter. If you specify a value for "PERLLIB", the library foldersspecified in the "Preferencesﾉ" dialog are appended to the value you specify.4. REMOTE CONTROL vs. DUPLEX MODETo illustrate the workings of Remote Control and Duplex mode and their differences, here are to AppleEvent logs from PCGI glue doing a Server push.First, the older glue using RCTL mode:-----------------------------------------------------------------------------------## The PCGI glue receives a request from WebStar:#'WWWｽ'¥sdoc{'----':'TEXT'(), kfor:ﾒanimateﾓ, user:'TEXT'(), pass:'TEXT'(), frmu:'TEXT'(), addr:ﾒ192.33.93.95ﾓ, svnm:ﾒneeracher.slip.ethz.chﾓ, svpt:ﾒ80ﾓ, scnm:ﾒ/Nu.acgiﾓ, ctyp:'TEXT'(), refr:ﾒhttp://neeracher.slip.ethz.ch/Nu.acgiﾓ, Agnt:ﾒMozilla/2.0b6a (Macintosh; I; PPC)ﾓ, Kact:ﾒACGIﾓ, Kapt:ﾒ/Nu.acgiﾓ, post:'TEXT'(), meth:ﾒGETﾓ, Kcip:ﾒ192.33.93.95ﾓ, Kfrq:ﾒGET /Nu.acgi?animate HTTP/1.0Referer: http://neeracher.slip.ethz.ch/Nu.acgiConnection: Keep-AliveUser-Agent: Mozilla/2.0b6a (Macintosh; I; PPC)Host: neeracher.slip.ethz.chAccept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */*ﾓ, Kcid:13, &inte:cans, &timo:2147483647}## The glue starts the Perl script in RCTL mode. Note how the header fields are passed# as environment variables:#misc¥dosc{'----':[alis(ﾇ0000000000D8000200000ﾉﾈ)], MODE:RCTL, SASE:{evcl:McPL, evid:SASE}, ENVT:[ﾒSERVER_SOFTWAREﾓ, ﾒMacHTTP/2.0ﾓ, ﾒGATEWAY_INTERFACEﾓ, ﾒCGI/1.1ﾓ, ﾒSERVER_PROTOCOLﾓ, ﾒHTTP/1.0ﾓ, ﾒQUERY_STRINGﾓ, ﾒanimateﾓ, ﾒREMOTE_ADDRﾓ, ﾒ192.33.93.95ﾓ, ﾒREQUEST_METHODﾓ, ﾒGETﾓ, ﾒSERVER_NAMEﾓ, ﾒneeracher.slip.ethz.chﾓ, ﾒSERVER_PORTﾓ, ﾒ80ﾓ, ﾒSCRIPT_NAMEﾓ, ﾒ/Nu.acgiﾓ, ﾒHTTP_REFERERﾓ, ﾒhttp://neeracher.slip.ethz.ch/Nu.acgiﾓ, ﾒHTTP_USER_AGENTﾓ, ﾒMozilla/2.0b6a (Macintosh; I; PPC)ﾓ, ﾒHTTP_CONNECTIONﾓ, ﾒKeep-Aliveﾓ, ﾒHTTP_HOSTﾓ, ﾒneeracher.slip.ethz.chﾓ, ﾒHTTP_ACCEPTﾓ, ﾒimage/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */*ﾓ]}## Perl immediately replies:#aevt¥ansr{}## Now Perl wants to push the header. It does this by sending the SASE event back to# the glue:#McPL¥SASE{}## The glue sends an almost empty data event to MacPerl to provoke an answer:#McPL¥DATA{INPT:{'----':ﾒ--More--ﾓ}}## Perl replies with the data:#aevt¥ansr{'----':ﾒHTTP/1.0 200 OKServer: MacHTTP/2.0MIME-Version: 1.0Content-Type: multipart/x-mixed-replace;boundary=EOM--EOMContent-type: text/plain1ﾓ, WANT:['----'], DONE:bool(ﾇ00ﾈ)}## The glue sends the data back to WebStar. First it replies to the original WebStar# request with an announcement that the answer is going to arrive in multiple parts:#aevt¥ansr{'----':ﾒ<SEND_PARTIAL>ﾓ}# # Now it sends the real data#'WWWｽ'¥SPar{'----':ﾒHTTP/1.0 200 OKServer: MacHTTP/2.0MIME-Version: 1.0Content-Type: multipart/x-mixed-replace;boundary=EOM--EOMContent-type: text/plain1ﾓ, Kmor:bool(ﾇ01ﾈ), Kcid:13}## Again, Perl wants to send more data:#McPL¥SASE{}## The glue asks Perl for more data:#McPL¥DATA{INPT:{'----':ﾒ--More--ﾓ}}## Perl sends the data:#aevt¥ansr{'----':ﾒ--EOMContent-type: text/plain2ﾓ, WANT:['----'], DONE:bool(ﾇ00ﾈ)}## And the glue sends the data to WebStar#'WWWｽ'¥SPar{'----':ﾒ--EOMContent-type: text/plain2ﾓ, Kmor:bool(ﾇ01ﾈ), Kcid:13}-----------------------------------------------------------------------------------Now the newer glue in DPLX mode. Note how only one AppleEvent per push is exchangedbetween the glue and MacPerl, instead of two:-----------------------------------------------------------------------------------## The PCGI glue receives a request from WebStar:#'WWWｽ'¥sdoc{'----':'TEXT'(), kfor:ﾒanimateﾓ, user:'TEXT'(), pass:'TEXT'(), frmu:'TEXT'(), addr:ﾒ192.33.93.95ﾓ, svnm:ﾒneeracher.slip.ethz.chﾓ, ... identical to RCTL case ... Connection: Keep-AliveUser-Agent: Mozilla/2.0b6a (Macintosh; I; PPC)Host: neeracher.slip.ethz.chAccept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */*ﾓ, Kcid:15, &inte:cans, &timo:2147483647}## The glue starts the Perl script in DPLX mode. #misc¥dosc{'----':[alis(ﾇ...ﾈ)], MODE:DPLX, SASE:{evcl:McPL, evid:SASE}, ENVT:[... identical to RCTL case ...]}## Perl immediately replies:#aevt¥ansr{}## Now Perl wants to push the header. Again, it does this by sending the SASE event # back to the glue, but this time, it already includes the data:#McPL¥SASE{'----':ﾒHTTP/1.0 200 OKServer: MacHTTP/2.0MIME-Version: 1.0Content-Type: multipart/x-mixed-replace;boundary=EOM--EOMContent-type: text/plain1ﾓ, WANT:['----'], DONE:bool(ﾇ00ﾈ), &inte:cans, &timo:3600}## The glue sends the data back to WebStar. First it replies to the original WebStar# request with an announcement that the answer is going to arrive in multiple parts:#aevt¥ansr{'----':ﾒ<SEND_PARTIAL>ﾓ}# # Now it sends the real data#'WWWｽ'¥SPar{'----':ﾒHTTP/1.0 200 OKServer: MacHTTP/2.0MIME-Version: 1.0Content-Type: multipart/x-mixed-replace;boundary=EOM--EOMContent-type: text/plain1ﾓ, Kmor:bool(ﾇ01ﾈ), Kcid:15}## Now the glue confirms the pushed data to Perl#aevt¥ansr{INPT:{'----':ﾒ--More--ﾓ}}## Again, Perl wants to send more data:#McPL¥SASE{'----':ﾒ--EOMContent-type: text/plain2ﾓ, WANT:['----'], DONE:bool(ﾇ00ﾈ), &inte:cans, &timo:3600}## And the glue sends the data to WebStar#'WWWｽ'¥SPar{'----':ﾒ--EOM
Content-type: text/plain
2
ﾓ, Kmor:bool(ﾇ01ﾈ), Kcid:15}## ... and confirms the pushed data to Perl#aevt¥ansr{INPT:{'----':ﾒ--More--ﾓ}}-----------------------------------------------------------------------------------
